<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>


  
  
  <title>FAQ</title>
</head>


<body style="color: rgb(80, 0, 0); background-color: rgb(255, 255, 240);" alink="#000099" link="#500000" vlink="#990099">


<div style="text-align: center;">
<h1 style="text-align: center;">FAQ</h1>



<div style="text-align: left;">
<blockquote style="font-weight: bold;" type="cite">I tried to compile the example.h from the coid front page:
  <br>

  <code><span style="font-weight: normal;">coidgen example.h
  </span><br style="font-weight: normal;">

  <span style="font-weight: normal;">make</span></code><br>

  
  <pre>That's the point where I'm stuck. What is supposed to happen here? It's just generating an example_dispatch.o.</pre>

</blockquote>


<span style="font-weight: bold;"></span>Ok, I think this is covered deeper in the documentation, under the 
'manual' section - generating communication layer - although maybe we 
should be really more detailed with these steps.
<br>


<br>

The coidgen should have generated example_dispatch.cpp, a makefile, and 
a folder 'client' with client .h and .cpp files.
<br>

All these files contain the communication layer generated for the 
'example' class. The example_dispatch.cpp file is the server side part, 
while the client/example_client.h is client side mirror class, a class 
that is used on the client side.
<br>


<br>

So what you should do is to create implementation file for server side, 
to implement methods declared in the example.h class. The coidgen won't 
do this for you, as it only generates an independent layer for specified 
class, that dispatches calls to the methods of the class.
<br>

So if you basically have your .h and .cpp files working, you can just 
decorate the declarations of class, and have coidgen generate the layer.
<br>


<br>

The client side is generated by coidgen as a whole, because it only kind 
of 'mirrors' the server (or remote) class and you usually don't have to 
do anything there. So it outputs the .h and .cpp file that you link with 
your client project, using the class with _client suffix in a way that 
you would use the original class, if it wasn't remote.
<br>


<br>

So - create two projects - server and client. To the server project add 
the example_dispatch.cpp, your custom example.cpp, and build. You should 
link it with the coid/coidsvc/coidsvc.a coid/comm/comm.a libraries, as 
it's done in the makefile (the makefile is there for these purposes, 
anyway). Output file should have the .dev extension, so that the coid 
would find it and make available for serving.
<br>


<br>

For the client side, you would probably add a .cpp file that creates the 
example_client class, connects it, and calls some methods to check that 
it works. The client project should contain the generated client files, 
and you should link it coid/comm/comm.a library too.<br>

<br>

<blockquote type="cite"><span style="font-weight: bold;">I use the command:
  </span><br style="font-weight: bold;">

  <span style="font-weight: bold;">g++ -Wall -I/usr/local example_client.cpp client.cpp /usr/local/coid/comm/comm.a
  </span><br style="font-weight: bold;">


  <span style="font-weight: bold;">I'm&nbsp;getting linker errors</span><br>

</blockquote>

You have to link it with dl and pthread library too, same as with the 
server side makefile, add
<br>

-lpthread -ldl
<br>

or add them to the command line, if you like
<br>


<br>

We don't generate makefile for client, as it's expected to be a part of 
another (client) project anyway, but we should state the linking 
requirements somewhere in the documentation.
<br>


<br>

<blockquote type="cite"><span style="font-weight: bold;">What is the username and password i need to use the coid console?
  </span><br>

</blockquote>


username root, empty password
<br>


<br>

<blockquote type="cite"><span style="font-weight: bold;">The makefiles work correctly as long as the program is in coid/apps/programname/.</span> 
</blockquote>


The makefiles are incorrectly generated, they use relative path to coid 
stuff as in our development environment, instead of the installed 
directories. That will be fixed in next release, thanks for pointing 
that out.
<br>

<br>

<blockquote type="cite"><span style="font-weight: bold;">devconf: I use this .devconf file:
  </span><br style="font-weight: bold;">

  <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; port 55099
  <br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; directory /usr/local/lib/coid/device
  <br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; default all
  <br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; service TestClass dir <i class="moz-txt-slash"><span class="moz-txt-tag">/</span>usr/local/coid/bin/device/TestClass<span class="moz-txt-tag">/</span></i>
  </code><br>

  <span style="font-weight: bold;">Configuring the server using the .devconf file works generally (changing the port, directory), but not the 'service' 
line. So I have to copy my .dev files always in the 
/usr/local/lib/coid/device folder, because 'make' puts them into the 
/usr/local/coid/bin/device folder. Is the 'service' command not working 
or is there a misconfiguration?
  </span><br>

</blockquote>


The 'dir' switch after the 'service' command sets the <span class="moz-txt-underscore"><span class="moz-txt-tag"></span><span style="font-weight: bold; font-style: italic;">working directory</span><span style="font-weight: bold; font-style: italic;" class="moz-txt-tag"></span></span> 
for instances of the service (a custom served class), not the location 
of the service. The devices to load are specified with the 'directory' 
line, but coid expects them to be located in their respective 
subdirectories, like if you specify
<br>

<code>&nbsp;&nbsp;&nbsp; directory /usr/local/lib/coid/device
</code><br>

coid would look for the .dev files in all direct subdirectories of it, 
for example
<br>

/usr/local/coid/bin/device/example/example.dev
<br>

would load thusly.
<br>

<br>

<blockquote type="cite"><span style="font-weight: bold;">Is there a difference between net_out and net_fetch? When should I 
use net_fetch?
  </span><br>

</blockquote>

With net_fetch, the server side method implementation returns a pointer 
or a reference to an existing object, that should be returned. With 
net_out, the implementation is expected to copy the result to the argument.
<br>

Example:
<br>

<code>&nbsp;&nbsp;&nbsp; opcd func( net_out myclass&amp; x) { x = blabla; }
<br>

&nbsp;&nbsp;&nbsp; opcd func( net_fetch myclass*&amp; x)&nbsp; { x = &amp;blabla; }
<br>

</code>
<br>

In the first case, dispatcher declares a myclass object, and calls the 
implementation:
<br>

<code>&nbsp;&nbsp;&nbsp; myclass x; func(x);
<br>

</code>Whereas in the second case, dispatcher declares just a pointer:
<br>

<code>&nbsp;&nbsp;&nbsp; const myclass* x; func(x);<br>

<br>

</code>Clearly, net_out involves an additional copy constructor call, because 
the temporary object must be filled, which may be costly if the class is 
complex. So we could use net_fetch for the dispatcher to retrieve just a 
pointer to the object.
<br>

You can wonder why it's not fetch-way default for net_out. That's 
because sometimes the implemented method would generate a temporary 
object by itself, and it cannot return a pointer to it since it dies on 
stack after exiting from the function. Also, sometimes copying is cheap.<br>

<br>

&nbsp;&nbsp;&nbsp;&nbsp;So general rule is - if the method returns something already contained 
within the class, that doesn't have trivial copy constructor, fetch it. 
Otherwise, use net_out.
<br>

<br>

<blockquote type="cite"><span style="font-weight: bold;">I have also found a remark that it's possible to link more than one
  </span><span style="font-weight: bold;">dispatch file to a device. How can I do that? Is there a way to
  </span><span style="font-weight: bold;">generate
a makefile doing that or do I have to do that manually? Is there an
advantage to have more classes in one device and not one&nbsp;class per
device? </span></blockquote>
You can just place all .cpp files in one folder - the makefile
generated by coidgen includes all .cpp files found. Or you can edit the
makefile (the SRC= line) to include files from specified folders where
the services you need were generated. With VisualC, just
place&nbsp;the&nbsp;.cpp files from all the classes you want into one
project outputting the .dev file. The resulting device contains all
coid-ified classes.
<br>


<br>

Your application can have 
multiple interfaces (that is, classes) accessible from outside, that 
work on a common kernel. So we have a data server, that has 3 or 4 
exported classes - a core server, that spawns it's unique instance at 
the beginning, that isn't accessed directly by end-user client, but by 
other servers and by other classes. Then there is a session class, that 
is created per connected user. Then there's a workspace class, that the 
session can have multiple open within the same communication channel. 
All the classes access the same stuff - a data repository, but provide 
different services, some are for the clients, some for central 
processing and so.
<br>


<br>

So, it becomes an advantage when you need it. With bigger projects, 
the need for this comes almost always.
<br>


<br>

Also, another scenario is that you have a server (non-coid primarily), 
that contains many internal classes and instances of that classes. Some 
classes can be decorated, and coid can be added as an additional access 
gateway. You can then connect through clients to the internal objects 
and retrieve a debug/status information, or execute methods and so on.
<br>

&nbsp;&nbsp;&nbsp;&nbsp; This creates some interesting possibilities, for example, since the 
dispatcher works with generic binstream, you can bind to an object with 
console, and execute methods right from there. And get the formated 
results back. With the XmlHttpRequest done all through a browser.
<br>


<br>

The coid stuff can be almost* non-invasive, that means the generated 
dispatcher is just and additional layer not used by the original server 
stuff. Although, "almost non-invasive" means that there must be mutex 
locks to prevent collision between coid accessing the object and other 
stuff. Coid generates the locks automatically, but only for access 
through coid, of course.
<br>

<br>

<blockquote type="cite"><span style="font-weight: bold;">Another important question especially for huge applications: When are
  </span><span style="font-weight: bold;">the exported classes getting created? After the request or as soon as
  </span><span style="font-weight: bold;">the device is loaded? Especially if this class needs big amounts of
  </span><span style="font-weight: bold;">memory it would make a significant difference. If it was created just
  </span><span style="font-weight: bold;">on request, there would be the nice possibility to do something like
  </span><span style="font-weight: bold;">load balancing. If you had a cluster of similar servers, you could
  </span><span style="font-weight: bold;">load all devices on all servers and implement in the clients a
  </span><span style="font-weight: bold;">routine to connect always to the server with the lowest load. Is
  </span><span style="font-weight: bold;">something like that possible?
  </span><br>

</blockquote>


It depends on the class. Normal classes are created upon request. But if 
the class contains <code>accept_connect_auto()</code> method, the framework server 
creates one instance of the object and client can connect using 
<code>connect_shared()</code> with id 0 to this one. If such&nbsp;class doesn't contain 
accept_connect, normal create-upon-request behavior is disabled.
<br>


<br>

Similarly, a presence of <code>accept_spawn()</code> method is understood as a 
requirement to call the accept_spawn method after creating the instance 
of class, so the object may execute whatever it needs, even without any 
client connected (what servers routinely do).
<br>


<br>

We considered to include load balancing to the coid, but later decided 
to create a load-balancer service (specific for our project), because 
the decisions about where to redirect were much more complicated than a 
simple load criterion.<br>

&nbsp;&nbsp;&nbsp;&nbsp;Anyway, this balancer does its job: it decides which server would be 
optimal, opens the service on that server, and returns a NODE_ADDRESS 
parameter to the client. Using that parameter the client can connect to 
the chosen target server.
<br>


<br>

It would be nice if that all could be transparent to the client, so it 
wouldn't have to know there's a balancer at all in the path. And it 
definitely can be done if there's strong desire for it. It will need a 
change the protocol, I think, but maybe it can piggyback with the 
update on the authentication thing.<br>

<br>

<br>

<blockquote style="font-weight: bold;" type="cite">Today I tried to compile my test program under windows. I generated the 
server and client files as usual (coidgen), but what's&nbsp; to do then? I 
get the usual Makefile for the server side. Should I use this (and use 
also gpp under windows) or should I generate the .dev file with Visual 
C++? If that's the case what settings have to be made?
  <br>

</blockquote>


We do not use the makefile for windows, we create standard projects in 
VisualC. We could possibly generate .dsp files to make it easier, but 
then there are also the VC6 and VC7 and VC8 formats ... but I think we 
should do it anyway, higher versions of VC should do the conversion 
automatically.
<br>


<br>

You should make the project output a .dev file, and link the project 
with the comm library.
<br>

<br>

<blockquote type="cite"><span style="font-weight: bold;">In coidc, about </span><span style="font-weight: bold;">the command 'find'. If I type 'find AccountMgr', I get 
'requested object not found'. Why that?
  </span><br>

</blockquote>


This is the ugliness of the console access. COID server uses several 
internal classes to perform various tasks, such as acceptors, plugin and 
service wrappers and so on. It keeps instances of these in a tree 
structure, so there's a parent relation and dependency links between 
them. This is used to properly kill selected objects and objects 
depending on them.
<br>


<br>

Now the .dev files are represented in the hierarchy as PluginCoid 
objects, their exported classes appear as ServiceCoid objects, and 
instances of the served classes are listed as ServiceInstanceCoid 
objects there.
<br>


<br>

So in the example, AccountMgr is managed class coming as either 
ServiceCoid or ServiceInstanceCoid (it's been spawned at the start). So 
proper way is to search for these, but this returns all of ServiceCoid 
classes.
<br>

There are commands finds and findi, that look for services or instances, 
respectively.
<br>

Use 'findi AccountMgr'.
<br>


<br>

There's one problem though, findi only looks for instances that were 
automatically spawned when the server had started (these are unique, and 
findi is internally used to find some core objects). For normal 
instances you must use find ServiceInstanceCoid &lt;name&gt;
<br>


<br>

Except that &lt;name&gt; of object is initially the class name, but the 
instance can rename it to whatever it wants (for example a user name). 
So it happens that the console instance names itself as "console 2 
alpha" and you cannot search for simple class name there then.
<br>

The remote console will be redesigned soon to clear these things out.<br>

<blockquote type="cite"><span style="font-weight: bold;">I'd like to test my demo program in the console. However if I 
change to the correct node and type 'help', there are not the methods 
listed as possible commands (like in the account manager for example). 
Do I have to specially export these methods for the console?
  </span><br>

</blockquote>


This certainly works but please be aware that you can only call methods 
on instances, not on the representation of a service (that is of the 
ServiceCoid - type).
<br>


<br>

You've probably called help on the service, and not the instance. 
Connect a client first, so the server creates an instance of your class, 
and then inspect it with coidc.
<br>

&nbsp;You can even create instances from the console, but just now you still 
need a ConnectionCoid object on the server to do it on. ConnectionCoid 
represents one tcp connection, and manages all instances open under it.
<br>

But here comes the trick: since the coidc is alone using a console 
service, so it's got a ConnectionCoid created already. When I did:
<br>


<br>

<code>find ServiceInstanceCoid
<br>

28 LogEntMgr 33 LogEntMgr 7 AccountMgr&nbsp; (auto)27 console 2 alpha32 
console 2 alpha24 HttpServ 0.126
<br>

HttpServ 0.123 MudCore&nbsp; (auto)30 ChatCore 0 alpha (auto)
<br>

<br>

27 cid
<br>

29
<br>

<br>

29 connect MudPort
<br>

ok
<br>

15:49:00 camn&nbsp; 35 MudPort&nbsp; a attaching [ServiceInstanceCoid]&nbsp;&nbsp;&nbsp; (MudPort)
<br>

15:49:00 camn&nbsp; 15 service&nbsp; i started instance of {MudPort} (35)
</code>


<br>


<br>


<br>

There are some bugs here, find* doesn't separate entries with anything; 
I could not use 'find ServiceInstanceCoid "console 2 alpha"' to find 
what id has got my console instance, I took it from the list the 'find 
ServiceInstanceCoid' gave me.
<br>

Then I ask for id of its ConnectionCoid object with 'cid'.
<br>

On that I can use 'connect' command to create instances of another classes.
<br>


<br>

As you can see, this gets somewhat complicated because you have to know 
the internals. And its ugly. But this shouldn't be necessary and the 
coidc should have be redesigned to make things simpler and elegant. 
Because of this it hadn't been updated and cleaned much so you have to 
be somewhat patient with it, sorry.
<br>

<br>


</div>


</div>


</body>
</html>
